/*
 *  BsdSocketAbstractionLayer.h
 *  NetTalk
 *
 *  Created by Andrey on 22/09/2008.
 *  Copyright 2008 ИУ7-2003. All rights reserved.
 *
 */

/** \file BsdSocketAbstractionLayer.h
	\brief Файл содержит описание структур и функций, скрывающих некоторые 
	механизмы работы BSD-сокетов.
 
	Описанные в этом файле функции и структуры помогают библиотеке NetTalk 
	использовать более удобный интерфейс при работе с наиболее муторными 
	аспектами BSD-сокетов, а именно — ожидание соединения на определённом порту
	и принятие (accept) соединения от клиента. (Автор вообще считает процессы 
	заполнения структур с названиями типа sockaddr_in.sin_addr.c_addr, 
	использования функции c названием вроде htons (или fcntl) античеловечными.) 
 
	Кроме этого введён новый тип — NTNetworkStream, являющийся на самом деле 
	обычным дескриптором сокета, однако такое название (по мнению автора) 
	является более соответствующим истине, чем обычный int (по крайней мере, для
	TCP-сокетов).
*/

#pragma once
#include "KBaseTypes.h"
#include "KAnsiCWrappers.h"

/** \def MAX_CLIENT_BACKLOG
	Константа, определяющая длину очереди заявок на подключение.
 */
#define MAX_CLIENT_BACKLOG	5
/**	\def INVALID_STREAM
	Константа, используемая для обозначения недействительного значения 
	дескриптора сокета.
 */
#define INVALID_STREAM		-1

/** \typedef typedef int NTNetworkStream;
 */
typedef int	NTNetworkStream;

/*
BEGIN_STRUCT_DECLARATION(NTPeerInfo)
	NTNetworkStream peerStream;
	UnicodeStringPtr peerAddress;
END_STRUCT_DECLARATION(NTPeerInfo)
*/

/**	\struct NtPeerInfo
	\brief Структура, предназанченная для хранения информации о подключившемся 
	клиенте, полученной от функции accept().
 */
BEGIN_STRUCT_DECLARATION(NTPeerInfo)
	NTNetworkStream peerStream;	
	//!< Сокет, соответствующий подключившемуся клиенту
	AsciiStringPtr peerAddress; 
	//!< IP-адрес подключившегося клиента в виде ASCIIZ-строки
END_STRUCT_DECLARATION(NTPeerInfo)

/**	\fn NTNetworkStream NTStartListeningOnPort(int port);
	\brief Функция запускает процесс ожидания на указанном порту.
 
	\param int port -- порт, на котором будет ожидаться подключение клиентов.
	\return Дескриптор сокета для подключившегося клиента, либо INVALID_STREAM в
	случае неудачи.
 */
NTNetworkStream NTStartListeningOnPort(int port);

/**	\fn NTPeerInfoPtr NTAcceptConnection(NTNetworkStream stream);
	\brief Функция принимает заявку на подключение от клиента на указанном 
	дескрипторе сокета.
 
	\param NTNetworkStream stream -- дескриптор сокета, к которому была попытка 
	подключиться.
	\return Указатель на структуру NTPeerInfo, содержающую информацию о 
	подключившемся клиенте, либо NULL в случае неудачи.
	\warning Ответственность за освобождение памяти по указателю, возвращаемому 
	функцией NTAcceptConnection, лежит на вызывающей стороне. 
 */
NTPeerInfoPtr NTAcceptConnection(NTNetworkStream stream);